HAL CCB Functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions

Functions

void HAL_CCB_SetUserData ( hal_ccb_handle_t * hccb , const void * p_user_data ) ¶

Store the user data into the CCB handle.

Parameters :

hccb – pointer to hal_ccb_handle_t structure.
p_user_data – pointer to the user data

const void * HAL_CCB_GetUserData ( const hal_ccb_handle_t * hccb ) ¶

Retrieve the user data from the CCB handle.

Parameters :: hccb – Pointer to CCB handle
Return values :: Pointer – to the user data

Initialization and De-initialization functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions_Group1

This subsection provides a set of functions to initialize and de-initialize the CCB peripheral:

The HAL_CCB_Init() API: Allows initializing the HAL CCB driver so it can be used for blob creation or usage. This API is the first API to call when using the HAL CCB, it takes 2 parameters as input:
- The HAL CCB handle: A pointer to a hal_ccb_handle_t structure
- The CCB instance : A value from the enumeration hal_ccb_t
The HAL_CCB_DeInit() API: Allows de-initializing the HAL CCB driver by:
- Disabling the CCB peripheral
- De-initializing the current handle object
- Resetting the handle global state to the HAL_CCB_STATE_RESET

Functions

hal_status_t HAL_CCB_Init ( hal_ccb_handle_t * hccb , hal_ccb_t instance ) ¶

Initialize the HAL CCB handle and associate it to an instance.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
instance – hal_ccb_t enumerated type variable to be set according to the physical instance

Return values :

HAL_INVALID_PARAM – Invalid param return when the CCB handle is NULL
HAL_OK – The HAL CCB driver is initialized according to the given handle and instance

void HAL_CCB_DeInit ( hal_ccb_handle_t * hccb ) ¶

De-initialize the CCB peripheral.

Parameters :: hccb – Pointer to a hal_ccb_handle_t structure

Reset function ¶

Note

This section is not available for STM32C562xx.

Wrapping symmetric key functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions_Group3

This subsection provides a set of functions to wrap the clear symmetric key:

HAL_CCB_ECDSA_WrapSymmetricKey(): Allows wrapping the clear symmetric key for ECDSA operations.
HAL_CCB_ECC_WrapSymmetricKey(): Allows wrapping the clear symmetric key for ECC operations.
HAL_CCB_RSA_WrapSymmetricKey(): Allows wrapping the clear symmetric key for RSA operations.

Functions

hal_status_t HAL_CCB_ECDSA_WrapSymmetricKey ( hal_ccb_handle_t * hccb , const uint32_t * p_in_user_key , hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , uint32_t * p_out_wrapped_user_key ) ¶

Wrap the clear symmetric key for ECDSA operations.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_user_key – Pointer to the clear AES key
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_out_wrapped_user_key – Pointer to the wrapped user key

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input user key pointer is NULL
- Wrapping key context pointer is NULL
- Output wrapped user key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_WrapSymmetricKey ( hal_ccb_handle_t * hccb , const uint32_t * p_in_user_key , hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , uint32_t * p_out_wrapped_user_key ) ¶

Wrap the clear symmetric key for ECC operations.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_user_key – Pointer to the clear AES key
p_wrapping_key_context – Pointer to the wrapping key context
p_out_wrapped_user_key – Pointer to the wrapped user key

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input user key is NULL
- Wrapping key context pointer key is NULL
- Output wrapped user key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_RSA_WrapSymmetricKey ( hal_ccb_handle_t * hccb , const uint32_t * p_in_user_key , hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , uint32_t * p_out_wrapped_user_key ) ¶

Wrap the clear symmetric key for RSA operations.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_user_key – Pointer to the clear AES key
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_out_wrapped_user_key – Pointer to the wrapped user key

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- The CCB handle is NULL
- Input user key is NULL
- Wrapping key context pointer key is NULL
- Output wrapped user key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

Process with software wrapping key functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions_Group4

This subsection provides a set of functions allowing to create and use a dedicated blob using a wrapped symmetric software key.

ECDSA operations:

HAL_CCB_ECDSA_SW_WrapPrivateKey(): Allows ECDSA Blob creation by wrapping user private key with a wrapped symmetric software key.
HAL_CCB_ECDSA_SW_GenerateWrapPrivateKey(): Allows ECDSA Blob creation by wrapping an RNG generated private key with a wrapped symmetric software key.
HAL_CCB_ECDSA_SW_Sign(): Allows ECDSA Blob usage for ECDSA signature with a wrapped symmetric software key.
HAL_CCB_ECDSA_SW_ComputePublicKey(): Allows ECDSA Blob usage for public key computation with a wrapped symmetric software key.

ECC operations:

HAL_CCB_ECC_SW_WrapPrivateKey(): Allows ECC Blob creation by wrapping user private key with a wrapped symmetric software key.
HAL_CCB_ECC_SW_GenerateWrapPrivateKey(): Allows ECC Blob creation by wrapping an RNG generated private key with a wrapped symmetric software key.
HAL_CCB_ECC_SW_ComputeScalarMul(): Allows ECC Blob usage for ECC compute scalar multiplication with a wrapped symmetric software key.

RSA operations:

HAL_CCB_RSA_SW_WrapPrivateKey(): Allows RSA Blob creation by wrapping user private key with a wrapped symmetric software key.
HAL_CCB_RSA_SW_ComputeModularExp(): Allows RSA Blob usage for RSA modular exponentiation with a wrapped symmetric software key.

Functions

hal_status_t HAL_CCB_ECDSA_SW_WrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , const uint8_t * p_in_clear_private_key , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecdsa_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECDSA Wrapping private Key with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to hal_ccb_ecdsa_curve_param_t structure
p_in_clear_private_key – Pointer to the clear private key
p_wrapping_key_context – Pointer to hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_out_wrapped_private_key_blob – Pointer to hal_ccb_ecdsa_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped user key pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECDSA_SW_GenerateWrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecdsa_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECDSA Wrapping an RNG generated Key with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecdsa_curve_param_t structure
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_out_wrapped_private_key_blob – Pointer to a hal_ccb_ecdsa_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped user key pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECDSA_SW_Sign ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecdsa_key_blob_t * p_in_wrapped_private_key_blob , const uint8_t * p_in_hash , uint8_t hash_size , hal_ccb_ecdsa_sign_t * p_out_signature ) ¶

Blob Usage: ECDSA Signature with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecdsa_curve_param_t structure
p_wrapping_key_context – Pointer to hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_in_wrapped_private_key_blob – Pointer to a hal_ccb_ecdsa_key_blob_t structure
p_in_hash – Pointer to the hash message
hash_size – Specify the size of the hash message
p_out_signature – pointer to a hal_ccb_ecdsa_sign_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped user key pointer is NULL
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input hash pointer is NULL
- Hash size pointer is zero
- Output signature pointer is NULL
- Output signature r_sign pointer is NULL
- Output signature s_sign pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECDSA_SW_ComputePublicKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecdsa_key_blob_t * p_in_wrapped_private_key_blob , hal_ccb_ecc_point_t * p_out_public_key ) ¶

Blob Usage: ECDSA Compute Public Key with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecdsa_curve_param_t structure
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_in_wrapped_private_key_blob – Pointer to a hal_ccb_ecdsa_key_blob_t structure
p_out_public_key – Pointer to a hal_ccb_ecc_point_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped user key pointer is NULL
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input wrapped private key blob wrapped key pointer is NULL
- Input hash pointer is NULL
- Output public key point_x pointer is NULL
- Output public key point_y pointer is NULL
- Output public key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_SW_WrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecc_mul_curve_param_t * p_in_curve_param , const uint8_t * p_in_clear_private_key , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecc_mul_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECC Wrapping private Key with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecc_mul_curve_param_t structure
p_in_clear_private_key – Pointer to the clear private key
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_out_wrapped_private_key_blob – Pointer to hal_ccb_ecc_mul_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input clear private key pointer is NULL
- Output wrapped private key blob
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_SW_GenerateWrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecc_mul_curve_param_t * p_in_curve_param , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecc_mul_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECC Wrapping an RNG generated Key with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecc_mul_curve_param_t structure
p_wrapping_key_context – Pointer a hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_out_wrapped_private_key_blob – Pointer to hal_ccb_ecc_mul_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped user key pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_SW_ComputeScalarMul ( hal_ccb_handle_t * hccb , const hal_ccb_ecc_mul_curve_param_t * p_in_curve_param , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_ecc_mul_key_blob_t * p_in_wrapped_private_key_blob , hal_ccb_ecc_point_t * p_in_point , hal_ccb_ecc_point_t * p_out_point ) ¶

Blob Usage: ECC Compute Scalar Multiplication with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecc_mul_curve_param_t structure
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_in_wrapped_private_key_blob – Pointer to hal_ccb_ecc_mul_key_blob_t structure
p_in_point – Pointer to hal_ccb_ecc_point_t structure
p_out_point – Pointer to hal_ccb_ecc_point_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped user key pointer is NULL
- Input wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped key pointer is NULL
- Input point pointer is NULL
- Input point x pointer is NULL
- Input point y pointer is NULL
- Output point pointer is NULL
- Input point x pointer is NULL
- Input point y pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_RSA_SW_WrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_rsa_param_t * p_in_param , const hal_ccb_rsa_clear_key_t * p_in_rsa_clear_private_key , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_rsa_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: RSA Wrap the private Key with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_param – Pointer to hal_ccb_rsa_param_t structure
p_in_rsa_clear_private_key – Pointer to hal_ccb_rsa_clear_key_t structure
p_wrapping_key_context – Pointer to to hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_out_wrapped_private_key_blob – Pointer to hal_ccb_rsa_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input parameters pointer is NULL
- Input RSA clear private key pointer key is NULL
- Input parameter exp_size_byte is zero
- Input parameter modulus_size_byte is zero
- Input parameter modulus pointer is NULL
- Input RSA clear private key exp pointer is NULL
- Input RSA clear private key phi pointer is NULL
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped phi pointer is NULL
- Output wrapped private key blob wrapped exp pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_RSA_SW_ComputeModularExp ( hal_ccb_handle_t * hccb , const hal_ccb_rsa_param_t * p_in_param , const hal_ccb_wrapping_sw_key_context_t * p_wrapping_key_context , const uint32_t * p_in_wrapped_user_key , hal_ccb_rsa_key_blob_t * p_in_wrapped_private_key_blob , const uint8_t * p_in_operand , uint8_t * p_out_modular_exp ) ¶

Blob Usage: RSA Compute Modular exponentiation with a wrapped symmetric software key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_param – Pointer to a hal_ccb_rsa_param_t structure
p_wrapping_key_context – Pointer to a hal_ccb_wrapping_sw_key_context_t structure
p_in_wrapped_user_key – Pointer to the wrapped user key
p_in_wrapped_private_key_blob – Pointer to hal_ccb_rsa_key_blob_t structure
p_in_operand – Pointer to the operand
p_out_modular_exp – Pointer to the output operation

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input parameters pointer is NULL
- Input parameter exp_size_byte is zero
- Input parameter modulus_size_byte is zero
- Input parameter modulus pointer is NULL
- Wrapping key context pointer key is NULL
- Provided init vector pointer is NULL
- Provided key size pointer is NULL
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input wrapped private key blob wrapped exp pointer is NULL
- Input wrapped private key blob wrapped phi pointer is NULL
- Output operand pointer is NULL
- Output modular exp pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

Process with hardware wrapping key functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions_Group5

This subsection provides a set of functions allowing to create and use a dedicated blob using a hardware key.

ECDSA operations:

HAL_CCB_ECDSA_HW_WrapPrivateKey(): Allows ECDSA Blob creation by wrapping user private key with a hardware key (DHUK or DHUK XOR).
HAL_CCB_ECDSA_HW_GenerateWrapPrivateKey(): Allows ECDSA Blob creation by wrapping an RNG generated key with a hardware key (DHUK or DHUK XOR).
HAL_CCB_ECDSA_HW_Sign(): Allows ECDSA Blob usage for ECDSA signature with a hardware key (DHUK or DHUK XOR).
HAL_CCB_ECDSA_HW_ComputePublicKey(): Allows ECDSA Blob usage for public key computation with a hardware key (DHUK or DHUK XOR).

ECC operations:

HAL_CCB_ECC_HW_WrapPrivateKey(): Allows ECC Blob creation by wrapping user private key with a hardware key (DHUK or DHUK XOR).
HAL_CCB_ECC_HW_GenerateWrapPrivateKey(): Allows ECC Blob creation by wrapping an RNG generated key with a hardware key (DHUK or DHUK XOR).
HAL_CCB_ECC_HW_ComputeScalarMul(): Allows ECC Blob usage for ECC compute scalar multiplication with a hardware key

RSA operations:

HAL_CCB_RSA_HW_WrapPrivateKey(): Allows RSA Blob creation by wrapping user private key with a hardware key (DHUK or DHUK XOR).
HAL_CCB_RSA_HW_ComputeModularExp(): Allows RSA Blob usage for RSA modular exponentiation with a hardware key (DHUK or DHUK XOR).

Functions

hal_status_t HAL_CCB_ECDSA_HW_WrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , const uint8_t * p_in_clear_private_key , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecdsa_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECDSA Wrapping the private Key with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to hal_ccb_ecdsa_curve_param_t structure
p_in_clear_private_key – Pointer to the clear private key
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_out_wrapped_private_key_blob – Pointer to hal_ccb_ecdsa_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input clear private key pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECDSA_HW_GenerateWrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecdsa_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECDSA Wrapping an RNG generated Key with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecdsa_curve_param_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_out_wrapped_private_key_blob – Pointer to a hal_ccb_ecdsa_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input clear private key pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECDSA_HW_Sign ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecdsa_key_blob_t * p_in_wrapped_private_key_blob , const uint8_t * p_in_hash , uint8_t hash_size , hal_ccb_ecdsa_sign_t * p_out_signature ) ¶

Blob Usage: ECDSA Signature with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecdsa_curve_param_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_in_wrapped_private_key_blob – Pointer to a hal_ccb_ecdsa_key_blob_t structure
p_in_hash – Pointer to the hash message
hash_size – Specify the size of the hash message
p_out_signature – Pointer to a hal_ccb_ecdsa_sign_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input hash pointer is NULL
- Hash size is zero
- Output signature pointer is NULL
- Output signature r_sign pointer is NULL
- Output signature s_sign pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECDSA_HW_ComputePublicKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecdsa_curve_param_t * p_in_curve_param , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecdsa_key_blob_t * p_in_wrapped_private_key_blob , hal_ccb_ecc_point_t * p_out_public_key ) ¶

Blob Usage: ECDSA Compute Public Key with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecdsa_curve_param_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_in_wrapped_private_key_blob – Pointer to a hal_ccb_ecdsa_key_blob_t structure
p_out_public_key – Pointer to a hal_ccb_ecc_point_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input wrapped private key blob wrapped key pointer is NULL
- Output public key point_x pointer is NULL
- Output public key point_y pointer is NULL
- Output public key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_HW_WrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecc_mul_curve_param_t * p_in_curve_param , const uint8_t * p_in_clear_private_key , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecc_mul_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECC Wrapping private Key with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecc_mul_curve_param_t structure
p_in_clear_private_key – Pointer to the clear private key
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_out_wrapped_private_key_blob – Pointer to hal_ccb_ecc_mul_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input clear private key blob pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_HW_GenerateWrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_ecc_mul_curve_param_t * p_in_curve_param , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecc_mul_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: ECC Wrapping an RNG generated Key with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecc_mul_curve_param_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_out_wrapped_private_key_blob – Pointer to hal_ccb_ecc_mul_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter modulus pointer is NULL
- Curve parameter prime_order pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped key pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_ECC_HW_ComputeScalarMul ( hal_ccb_handle_t * hccb , const hal_ccb_ecc_mul_curve_param_t * p_in_curve_param , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_ecc_mul_key_blob_t * p_in_wrapped_private_key_blob , hal_ccb_ecc_point_t * p_in_point , hal_ccb_ecc_point_t * p_out_point ) ¶

Blob Usage: ECC Compute Scalar Multiplication with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_curve_param – Pointer to a hal_ccb_ecc_mul_curve_param_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_in_wrapped_private_key_blob – Pointer to hal_ccb_ecc_mul_key_blob_t structure
p_in_point – Pointer to hal_ccb_ecc_point_t structure
p_out_point – Pointer to hal_ccb_ecc_point_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input curve parameters pointer is NULL
- Curve parameter abs_coef_a pointer is NULL
- Curve parameter coef_b pointer is NULL
- Curve parameter point_x pointer is NULL
- Curve parameter point_y pointer is NULL
- Curve parameter prime_order_size_byte is zero
- Curve parameter modulus_size_byte is zero
- Curve parameter coef_sign_a is zero
- Input clear private key blob pointer is NULL
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input wrapped private key blob wrapped key pointer is NULL
- Input point pointer is NULL
- Input point x pointer is NULL
- Input point y pointer is NULL
- Output point pointer is NULL
- Output point x pointer is NULL
- Output point y pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_RSA_HW_WrapPrivateKey ( hal_ccb_handle_t * hccb , const hal_ccb_rsa_param_t * p_in_param , const hal_ccb_rsa_clear_key_t * p_in_rsa_clear_private_key , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_rsa_key_blob_t * p_out_wrapped_private_key_blob ) ¶

Blob Creation: RSA Wrapping private Key with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_param – Pointer to hal_ccb_rsa_param_t structure
p_in_rsa_clear_private_key – Pointer to hal_ccb_rsa_clear_key_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_out_wrapped_private_key_blob – Pointer to hal_ccb_rsa_key_blob_t structure

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input parameters pointer is NULL
- Input parameter exp_size_byte is zero
- Input parameter modulus_size_byte is zero
- Input parameter modulus pointer is NULL
- Input RSA clear private key exp pointer is NULL
- Input RSA clear private key phi pointer is NULL
- Output wrapped private key blob pointer is NULL
- Output wrapped private key blob IV pointer is NULL
- Output wrapped private key blob tag pointer is NULL
- Output wrapped private key blob wrapped exp pointer is NULL
- Output wrapped private key blob wrapped phi pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

hal_status_t HAL_CCB_RSA_HW_ComputeModularExp ( hal_ccb_handle_t * hccb , const hal_ccb_rsa_param_t * p_in_param , hal_ccb_wrapping_hw_key_type_t wrapping_hw_key_type , hal_ccb_rsa_key_blob_t * p_in_wrapped_private_key_blob , const uint8_t * p_in_operand , uint8_t * p_out_modular_exp ) ¶

Blob Usage: RSA Compute Modular exponentiation with a hardware key.

Parameters :

hccb – Pointer to a hal_ccb_handle_t structure
p_in_param – Pointer to a hal_ccb_rsa_param_t structure
wrapping_hw_key_type – Wrapping key with a hal_ccb_wrapping_hw_key_type_t type
p_in_wrapped_private_key_blob – Pointer to hal_ccb_rsa_key_blob_t structure
p_in_operand – Pointer to the operand
p_out_modular_exp – Pointer to the output operation

Return values :

HAL_INVALID_PARAM – The function return an Invalid param in the following cases:
- The CCB handle is NULL
- Input parameters pointer is NULL
- Input parameter exp_size_byte is zero
- Input parameter modulus_size_byte is zero
- Input parameter modulus pointer is NULL
- Input wrapped private key blob pointer is NULL
- Input wrapped private key blob IV pointer is NULL
- Input wrapped private key blob tag pointer is NULL
- Input wrapped private key blob wrapped exp pointer is NULL
- Input wrapped private key blob wrapped phi pointer is NULL
- Output operand pointer is NULL
- Output modular exp pointer is NULL
HAL_ERROR – Error detected
HAL_OK – Operation completed successfully

Peripheral State, Error functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions_Group6

Functions

hal_ccb_state_t HAL_CCB_GetState ( const hal_ccb_handle_t * hccb ) ¶

Return the CCB state.

This subsection provides a set of functions to retrieve the state and the error codes

HAL_CCB_GetState() retrieve the global CCB state.
HAL_CCB_GetLastErrorCodes() retrieve the last CCB error code.
HAL_CCB_SetUserData() store user data pointer into the handle.
HAL_CCB_GetUserData() retrieve user data pointer from the handle.

Parameters :: hccb – pointer to hal_ccb_handle_t structure.
Return values :: hal_ccb_state_t – CCB global state.

uint32_t HAL_CCB_GetLastErrorCodes ( const hal_ccb_handle_t * hccb ) ¶

Return the CCB handle error code.

Parameters :: hccb – pointer to hal_ccb_handle_t structure.
Return values :: uint32_t – CCB last error codes.

void HAL_CCB_SetUserData ( hal_ccb_handle_t * hccb , const void * p_user_data )

Store the user data into the CCB handle.

Parameters :

hccb – pointer to hal_ccb_handle_t structure.
p_user_data – pointer to the user data

const void * HAL_CCB_GetUserData ( const hal_ccb_handle_t * hccb )

Retrieve the user data from the CCB handle.

Parameters :: hccb – Pointer to CCB handle
Return values :: Pointer – to the user data

Static Inlines functions ¶

Note

This section is not available for STM32C562xx.

group CCB_Exported_Functions_Group7

This section provides functions to manage CCB flags:

HAL_CCB_GetFlag() :Return the state of a flag

Functions

uint32_t HAL_CCB_GetFlag ( const hal_ccb_handle_t * hccb , uint32_t flag ) ¶

Check whether the specified CCB status flag is set or not.

Parameters :

hccb – Specifies the ccb handle
flag – Specifies the flag to check, this parameter can be one of the following values:
- HAL_CCB_FLAG_BUSY CCB busy or PKA RAM is being cleared following a peripheral reset
- HAL_CCB_TAMP_EVT_RNG RNG TAMP Event flag
- HAL_CCB_TAMP_EVT_SAES SAES TAMP Event flag
- HAL_CCB_TAMP_EVT_PKA_RAM_REG PKA Register TAMP Event flag
- HAL_CCB_TAMP_EVT_PKA_OPR PKA Operation TAMP Event flag
- HAL_CCB_TAMP_EVT_CCB CCB TAMP Event flag

Return values :

uint32_t – The state or value of flag.